07 - 观测与落地

前置：01 到 06 篇。

本篇回答：前面那些改动到底起没起作用 —— 以及怎么避免"token 降了、任务反而做不成了"这种最常见的失败。

本篇会用到的词：

词	意思
护栏指标	不是优化目标、但一旦变差就必须回滚的指标。任务成功率是这一层唯一的护栏
上下文构成	一次请求的 token 按去向拆开的分布，01 篇那五项
轮次数	完成一个任务用掉的模型往返次数。卸载类手段会推高它
对照组	关掉全部上下文管理的那一组。没有它，任何改进数字都无法解读

一、五个指标

只盯 token 是这一层最典型的失败方式。把上下文砍到只剩一句话，①②③④全都好看，⑤崩掉 —— 而⑤往往是最后才被发现的，因为它需要跑完整任务才测得出来。

二、怎么打点

上下文构成不会自己出现在 trace 里，要主动写进去。属性命名沿用 Agent 可观测性那一套的习惯：

# 在每次模型调用的 span 上挂这几组属性。
# 关键是「拆开记」——只记一个 input_tokens 总数，事后没法回答任何问题。
span.set_attributes({
    # ① 构成：五个去向各自的 token 数
    "ctx.tools_tokens":      12_000,
    "ctx.system_tokens":         800,
    "ctx.history_tokens":     18_000,
    "ctx.tool_result_tokens": 140_000,
    "ctx.injected_tokens":       300,   # 记忆 ＋ 检索

    # ② 缓存：直接来自 usage，不要自己推算
    "ctx.cache_read_tokens":     0,
    "ctx.cache_creation_tokens": 0,

    # ③ 这一轮做了什么上下文管理动作，以及各自清掉多少
    #    来自 response.context_management.applied_edits
    "ctx.edits_applied":        "clear_tool_uses_20250919",
    "ctx.cleared_tokens":       50_000,
    "ctx.compaction_occurred":  False,

    # ④ 真实成本：遍历 usage.iterations，别用顶层字段（03 篇第三个坑）
    "ctx.billed_input_tokens":  sum(i["input_tokens"] for i in usage["iterations"]),
    "ctx.billed_output_tokens": sum(i["output_tokens"] for i in usage["iterations"]),
})

响应里可以直接取到的两处，不用自己算：

response.context_management.applied_edits —— 这次应用了哪些编辑策略、清了几次工具调用、清掉多少 token。流式响应里它在最后的 message_delta 事件中
response.usage.iterations —— 每次采样迭代的输入输出量，压缩那一次单独一项

三、八条反模式

三类的发现成本递增着往左走：工程细节类看一眼 cache_read_input_tokens 就能发现；手段类要算账才知道；认识类只有在跑完一轮完整对照实验之后才会暴露。

四、对照实验怎么做

# 四组，跑同一批真实任务。关键是 A 组必须存在 ——
# 没有"什么都不做"的基线，其余三组的数字都无法解读。
ARMS = {
    "A_baseline":   {},                                       # 全关
    "B_tools":      {"tool_search": True},                    # 只做工具搜索（05 篇）
    "C_tools_clear":{"tool_search": True, "clear": True},     # 加工具结果裁剪（03 篇）
    "D_all":        {"tool_search": True, "clear": True, "compact": True},
}

# 每组至少 50 个任务，记五个指标。判读规则：
#   - ⑤ 成功率相对 A 组下降超过误差范围 → 这一组直接否决，不管 token 省了多少
#   - ⑤ 持平时，比 ④ 每任务总 token；同时看轮次数有没有明显上涨
#   - ② 缓存命中率相对 A 组下降 → 检查是不是 clear_at_least 没配（06 篇第五节）

逐组叠加而不是一次全开，是因为这几种手段互相影响：工具搜索做完之后，上下文构成变了，原来定的裁剪阈值可能已经不合适。一次全开的话，出了问题不知道是哪一项的责任。

五、四步落地

第①步最容易被跳过，也最能省事 —— 02 篇第五节那个灌水实验两小时能跑完，如果结果是"完全不掉分"，后面三步就都不用做了。

六、小结

五个指标里，任务成功率与轮次数是护栏而不是目标；只盯 token 会优化到功能坏掉
每任务总 token 要遍历 usage.iterations 求和、并按任务而非按请求聚合，否则卸载和压缩都会给出假象
applied_edits 和 iterations 可以从响应里直接取，不用自己推算
八条反模式里，工程细节类看一眼缓存命中率就能发现，认识类要跑完整对照实验才会暴露
对照实验逐组叠加，不要一次全开 —— 几种手段互相影响，一起上就分不清责任
落地顺序：先量 → 治工具定义 → 裁工具结果 → 才是压缩；卸载是架构改动，放到最后考虑

← 回到专题索引　|　Agent 记忆专题

一、五个指标​

二、怎么打点​

三、八条反模式​

四、对照实验怎么做​

五、四步落地​

六、小结​